Manage Appointment API
How to use the API
Here's an overview of the features included in this API, what they do and what you can use them for:
| API Feature | What it does | What it's used for |
|---|---|---|
| Get API Version | Retrieves the full version number of the API (major, minor and patch version numbers). | Viewing the API version. |
| Get appointment availability (RFS or site visit) | Retrieve available appointments for an order. | Viewing available appointments for an order to be scheduled against. |
| Update or reserve appointment (RFS or site visit) | Reserve or update an existing appointment. | Booking or rescheduling an appointment. |
| GGet appointment details (RFS or site visit) | Retrieve appointment details for an order. | Viewing appointments for an order. |
Appointments
Appointments are dates and times that an order can be scheduled.
There are two types of appointments:
- Site visit appointments are an appointment where a technician will visit a site to complete some work (e.g. Scope, Install or CSE).
- RFS appointments do not require a site visit.
Site visit appointments
Site visit appointments are dates and times that a site visit can be performed. Site visit appointments are returned as morning appointments (AM) from 08:00 - 12:00 and afternoon appointments (PM) from 13:00 - 17:00.
Morning (AM) site visit
The following are examples of morning site visit values under a siteVisitAppointment object.
| Element | Example |
|---|---|
| startDateTime | 2024-09-29T08:00:00+13:00 |
| endDateTime | 2024-09-29T12:00:00+13:00 |
Afternoon (PM) site visit
The following are examples of afternoon site visit values under a siteVisitAppointment object.
| Element | Example |
|---|---|
| startDateTime | 2024-09-29T13:00:00+13:00 |
| endDateTime | 2024-09-29T17:00:00+13:00 |
Site Visit Appointment types and lead times
Appointment types and associated lead-times are listed in the following table.
| Appointment type | Other active appointments | Offer type | Minimum lead time | Inter-appointment lead time | Examples |
|---|---|---|---|---|---|
| Scope | n/a | Residential (default) | 1 day | 3 days or more | Scope (Day 1) Install (Day 4) |
| Install (or Install + CSE) | Scope | Residential (default) | 1 day | 3 days or more | Scope (Day 1) Install (Day 4) |
| Install (or Install + CSE) | None | Residential (default) | 4 days | n/a | Install (Day 4) |
| CSE (standalone) | n/a | Residential (default) | 2 days | n/a | CSE (Day 2) |
| Scope | n/a | Business or Educational | 1 day | 5 days or more | Scope (Day 1) Install (Day 6) |
| Install (or Install + CSE) | Scope | Business or Educational | 6 days | 5 days or more | Scope (Day 1) Install (Day 6) |
| Install (or Install + CSE) | None | Business or Educational | 6 days | n/a | Install (Day 6) |
| CSE (standalone) | n/a | Business or Educational | 2 days | n/a | - |
RFS appointments
The following RFS Appointment types and lead times apply:
- RFS appointments are available hourly throughout the day from 6AM to 9PM, Monday to Sunday.
- RFS lead times require a minimum timeframe of 1 hour (rounded up to the nearest hour) to allow for system processing before they’re able to be scheduled for the next hourly RFS appointments.
Examples:
- An order request created at 9:05AM would have a first available RFS for 11AM.
- An order request created at 4:55PM would have a first available RFS of 6PM.
- An order request created at 3:02PM would have a first available RFS of 5PM.
The following are examples of morning site visit values under a siteVisitAppointment object.
| Element | Example |
|---|---|
| startDateTime | 2024-09-29T08:00:00+13:00 |
| endDateTime | 2024-09-29T12:00:00+13:00 |
RFS dates
The following are examples of RFS dates.
| Element | Value | Example |
|---|---|---|
| rfsAppointmentDateTime | Time on the hour | 2024-12-15T10:00:00.000+13:00 |
Rescheduling inter-appointments
In cases where multiple appointments are needed for an Order, you may need to sequence your Reserve Appointment Requests to avoid failing one or more of the validation rules. Learn more about Business Rule Chorus-BIC005-14.
Example:
You have reserved a Scope appointment on 30 June 2024 and an associated Install appointment is reserved on 3 July 2024, for a residential customer. The customer requests you reschedule the Scope appointment to 3 July 2024. However, the lead-time validation rules prevent you from changing the Scope appointment to 3 July until you have rescheduled the Install appointment.
To reschedule the Scope and Install appointments, you will need to:
| Step | Action |
|---|---|
| 1. | Confirm there are Scope appointments available on 3 July 2024. |
| 2. | Use the Query Appointment Availability to request a list of available Scope Appointments using: - timeSlotFilterStartDateTime: 3 July 2024 - validateInterAppointmentLeadTime: false This will return a list of available appointments, ignoring the appointment lead-time rules. If there is an available appointment for 3 July, you can reschedule the Install appointment on or after 8 July 2024. |
| 3. | Reschedule the Install Appointment: - Use the Query Appointment Availability to request a list of available Install appointments from 8 July 2024. - Reschedule the Install Appointment to or after 8 July 2024. |
| 4. | Reschedule the Scope Appointment to 3 July 2024. |
Retrieving appointment details for an order with no appointment
If the GET appointment details endpoint for site visit or RFS does not return a start date or time, then there is no appointment scheduled. To progress with the order, you need to schedule an appointment.
Scope added after order submission
During order assessment, operational teams may determine additional site visits are required for an order. The operational team will update the order to ensure the new site visit is added. When this occurs, you need to schedule the order, ensuring you also schedule the additional site visit.
Note: For more information on all available resources, attributes, parameters, field types, length and other restrictions, see the API Specification.